Skip to content

Add AnalysisPlugin interface for tracking analysis decisions#3

Draft
Copilot wants to merge 353 commits intomasterfrom
copilot/fix-b557e6d0-f9ba-4e80-b858-62aea0092bf6
Draft

Add AnalysisPlugin interface for tracking analysis decisions#3
Copilot wants to merge 353 commits intomasterfrom
copilot/fix-b557e6d0-f9ba-4e80-b858-62aea0092bf6

Conversation

Copy link

Copilot AI commented Oct 6, 2025

Implements support for AnalysisPlugin as described in bndtools#6772, providing a way to observe and track analysis decisions made by the Analyzer during bundle creation.

Problem

When building OSGi bundles, bnd analyzes code and determines version ranges for imported packages based on various factors (provider types, explicit directives, version policies). However, there was no way to observe these decisions or understand why a particular version range was chosen, making debugging and auditing difficult.

Solution

This PR introduces a new AnalysisPlugin interface that receives callbacks during the analysis phase with detailed information about version decisions:

public interface AnalysisPlugin extends OrderedPlugin {
    void reportImportVersion(Analyzer analyzer, PackageRef packageRef, 
                           String version, String reason) throws Exception;
    
    default void reportAnalysis(Analyzer analyzer, String category, 
                               String details) throws Exception {}
}

The plugin is called during Analyzer.augmentImports() and provides:

  • The package being imported
  • The calculated version range
  • A human-readable reason (e.g., "provider type detected", "consumer type (default)", "explicit provide directive")

Example Usage

public class LoggingAnalysisPlugin implements AnalysisPlugin {
    @Override
    public void reportImportVersion(Analyzer analyzer, PackageRef packageRef, 
                                   String version, String reason) {
        System.out.printf("Import: %s -> %s (%s)%n", 
                         packageRef.getFQN(), version, reason);
    }
}

In a bnd.bnd file:

-plugin: com.example.LoggingAnalysisPlugin

Changes

  • New interface: aQute.bnd.service.AnalysisPlugin following the existing plugin architecture pattern
  • Analyzer modifications: Added callback invocation in augmentImports() with helper methods buildVersionReason() and reportImportVersion()
  • Comprehensive tests: 3 test scenarios covering plugin invocation, provider/consumer reporting, and ordering
  • Documentation: Complete guide with examples in docs/_plugins/analysisplugin.md

Testing

All tests pass with no regressions:

  • New AnalysisPluginTest: 3 tests ✅
  • Existing Analyzer tests: all passing ✅
  • Existing Plugin tests: all passing ✅
  • Total: 1565 tests, 6 pre-existing unrelated failures

Use Cases

  • Debugging: Understand why bnd chose a particular version range
  • Compliance: Log analysis decisions for audit purposes
  • Optimization: Identify opportunities to optimize version policies
  • Documentation: Generate reports about bundle dependencies

Closes bndtools#6772

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • bndtools.jfrog.io
    • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -Xms1024m -Xmx2048m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant -cp /home/REDACTED/.gradle/wrapper/dists/gradle-8.14-bin/38aieal9i53h9rfe7vjup95b9/gradle-8.14/lib/gradle-daemon-main-8.14.jar -javaagent:/home/REDACTED/.gradle/wrapper/dists/gradle-8.14-bin/38aieal9i53h9rfe7vjup95b9/gradle-8.14/lib/agents/gradle-instrumentation-agent-8.14.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 8.14 (dns block)
  • scans-in.gradle.com
    • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -Xms1024m -Xmx2048m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant -cp /home/REDACTED/.gradle/wrapper/dists/gradle-8.14-bin/38aieal9i53h9rfe7vjup95b9/gradle-8.14/lib/gradle-daemon-main-8.14.jar -javaagent:/home/REDACTED/.gradle/wrapper/dists/gradle-8.14-bin/38aieal9i53h9rfe7vjup95b9/gradle-8.14/lib/agents/gradle-instrumentation-agent-8.14.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 8.14 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

Suggest to add support for analysis plugins as described in @bndtools/bndbndtools/issues/6772


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI changed the title [WIP] Suggest to add support for analysis plugins as described in @bndtools/bnd/issues/6772 Add AnalysisPlugin interface for tracking analysis decisions Oct 6, 2025
Copilot AI requested a review from laeubi October 6, 2025 08:39
* @param details detailed information about the decision
* @throws Exception if an error occurs during processing
*/
default void reportAnalysis(Analyzer analyzer, String category, String details) throws Exception {

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This method is not called anywhere. Is it really needed?

chrisrueger and others added 23 commits January 2, 2026 12:55
prepend the /releases/7.2.0/ to the .js and .css files so that the pagefind search will search the 7.2.0 pagefindindex which we also copied over during release.

this is only needed here once, since the previous commit makes sure this will happen automatically for next releases

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
…from-search

Docs exclude 7.2.0 from pagefind search  (prevent duplicate search results)
…nativecode-from-reorderclause

skip reorderClause() for Bundle-NativeCode
biz.aQute.bnd.annotation: compile with java 8
Mention the removal in 8.0.0 in the readme and .bnd files

Docs: Add deprecation notice for biz.aQute.tester

Added a deprecation warning to the testing documentation indicating that the default test 'biz.aQute.tester' is deprecated as of bnd 7.2.0 and will be removed in 8.0.0. Users are advised to migrate to JUnit 5 and use 'biz.aQute.tester.junit-platform'.

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Deprecate biz.aQute.tester and biz.aQute.junit
Signed-off-by: Peter Kirschner <peter@klib.io>
- added testcase for non-jar repo references tp prove the current problems of bndtools#6660

- Fix file extension check for library containers. Changed the file name check from 'lib' to '.lib' to correctly identify library containers based on file extension.
There are other places where ".lib" is checked already.

- Added handling for ZipException in ProjectBuilder and ResourceBuilder to support non-JAR files (e.g., .so, .dylib) referenced in repositories. This prevents errors when such files are encountered (e.g. via ${repo} macro) and ensures dependencies and resources are processed gracefully.

- Also do not add non-jar files as library entries in BndContainerInitializer

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Corrected the description of the VERSION field to clarify that it is an OSGi version range and added a note about version range semantics.

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
…include-dynlib-resources

fix unable to reference non-jar resources in MavenBndRepo and repo macro
Finetune and reduce logging noise

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
…e-lognoise-on-release

Update release logging to use bndProject name
…2/1.14.2)

- Modified BundleEngine.executeBundle() to accept and pass ExecutionRequest parameter
- Updated BundleDescriptor.executeChild() to accept ExecutionRequest instead of separate listener and params

Add ExecutionRequestFactory to propagate execution context for JUnit Platform 1.13+

Implemented ExecutionRequestFactory that uses reflection to properly propagate the internal NamespacedHierarchicalStore from parent ExecutionRequest to child requests. This is necessary for JUnit Platform 1.13+ compatibility.

The factory:
- Detects if reflection is available and needed
- Uses internal Store API if available (JUnit Platform 1.13+)
- Falls back to public constructor for older versions
- Handles failures gracefully

Updated BundleDescriptor to use the factory instead of directly creating ExecutionRequest.

- Add detailed comment explaining why internal JUnit Platform API is accessed

Updated BundleEngineTest to include ExecutionRequestFactory class in the engine bundle for tests. This class was added in the JUnit Platform 1.13+ compatibility changes but wasn't included in the test bundle setup.

All tests now pass successfully.

Update JUnit Jupiter/Platform versions to 5.11.4/1.11.4

Updated junit.jupiter.version and junit.platform.version to 5.11.4/1.11.4 to test with newer versions. These versions are compatible and all 136 tests pass.

Fix JUnit5 test classes to use static @BeforeAll methods for 5.13+ compatibility

Made @BeforeAll methods static in JUnit5ContainerFailure and JUnit5ContainerError test classes.

In JUnit 5.13+, non-static @BeforeAll methods are now detected as discovery errors (causing DiscoveryIssueException) rather than execution failures. This was causing the exitCode_countsJupiterContainerErrorsAndFailures() test to fail - expecting exit code 2 (two container failures) but getting exit code 1 (discovery error).

Making the @BeforeAll methods static ensures they properly execute and fail as intended by the test, maintaining compatibility with JUnit Platform 1.13+.

fix ConfigVersionsTest

replace deprecated method getParameterTypeNames

Replaces calls to getMethodParameterTypes with getParameterTypeNames when creating and resolving MethodSelectors. This aligns with updated API usage and ensures correct parameter type handling.

Refactor ExecutionRequest to use static create() methods

Replaces use of internal constructors with reflection-based invocation of static create() methods for ExecutionRequest, improving compatibility with JUnit Platform 1.13+ and future versions. This change also updates the logic to detect and use the appropriate static method signatures, and removes reliance on direct constructor access.

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

Update JUnit Jupiter and Platform to 5.14.1/1.14.1

Bump JUnit Jupiter and Platform versions to 5.14.2 and 1.14.2 in cnf/ext/junit.bnd, Gradle, and Maven plugin parent POM to keep dependencies up to date and consistent across the project.

This is the latest version in the 5.x / 1.x range and also the version used by Eclipse

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Co-Authored-By: chrisrueger <188422+chrisrueger@users.noreply.github.com>
…spaced-hierarchical-store

Fix Junit Platform 1.13+ Support (up to JUnit Jupiter and Platform to 5.14.2/1.14.2)
Updated installation instructions and badge links in README.

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
as discussed today. The current implementation was a dead end and we will move it to another part of the build. It was needed to release bnd itself but should not be used anywhere outside

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
…releaser

deprecate sonatype release mode for 7.3.0
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
peterkir and others added 22 commits March 18, 2026 14:58
… baselining

Signed-off-by: Peter Kirschner <peter@klib.io>
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
Signed-off-by: Peter Kirschner <peter@klib.io>
Signed-off-by: Peter Kirschner <peter@klib.io>
Signed-off-by: Peter Kirschner <peter@klib.io>
Signed-off-by: Peter Kirschner <peter@klib.io>
Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
…e-for-p2-parsing-bug

Fix Eclipse feature.xml match rule version range computation
Signed-off-by: Peter Kirschner <peter@klib.io>
Signed-off-by: Peter Kirschner <peter@klib.io>
…quired-features-refresh

Fix Resolution View stale data on empty loader selection
…tation-into-template

Migrate bnd docs to just-the-docs Jekyll theme with dark mode toggle
Bumps [json](https://github.com/ruby/json) from 2.18.1 to 2.19.2.
- [Release notes](https://github.com/ruby/json/releases)
- [Changelog](https://github.com/ruby/json/blob/master/CHANGES.md)
- [Commits](ruby/json@v2.18.1...v2.19.2)

---
updated-dependencies:
- dependency-name: json
  dependency-version: 2.19.2
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
- now 00-overview.md is accessible under /commands/overview.html
- and the generated index.md (from the index CLI command) under /commands/index.html
- navbar works too.

TODO we should think about if we adopt this pattern for _heads and _macros  too

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
…s/json-2.19.2

build(deps-dev): bump json from 2.18.1 to 2.19.2 in /docs
…-clash

Docs: fix index.md clash for commands
Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.33.0 to 4.34.1.
- [Release notes](https://github.com/github/codeql-action/releases)
- [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md)
- [Commits](github/codeql-action@b1bff81...3869755)

---
updated-dependencies:
- dependency-name: github/codeql-action
  dependency-version: 4.34.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
…ons/github/codeql-action-4.34.1

build(deps): bump github/codeql-action from 4.33.0 to 4.34.1
mark the unused instruction as deprecated as suggested in PR bndtools#7158
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
@laeubi laeubi force-pushed the copilot/fix-b557e6d0-f9ba-4e80-b858-62aea0092bf6 branch from 06cae53 to 4e2cd4e Compare March 22, 2026 08:19
chrisrueger and others added 4 commits March 22, 2026 10:28
- avoid section headers
- consistent use of 00-overview.md pages
- improve the "References" section in the Home sidebar section to make a bit more sense

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
- Copy tocbot 4.21.1 (JS + CSS) into docs/js/ and docs/css/ so no
  external CDN is required
- Load them via head_custom.html using Jekyll relative_url
- Add sticky #bnd-toc panel styles in custom.scss (visible only on
  screens >= 1400px, theme-aware colours, active-link highlight)
- Initialise Tocbot inside jtd.onReady in custom.js; panel is only
  injected when the page has >= 2 h2/h3 headings; smooth-scroll enabled

Agent-Logs-Url: https://github.com/bndtools/bnd/sessions/45891f3a-7895-4a79-8695-c6debdb88380

use latest v4.36.4 and add license
css tweaks
remove duplicaated TOC on overview pages

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Co-Authored-By: chrisrueger <188422+chrisrueger@users.noreply.github.com>
…-sticky-toc

docs: Add right-side sticky "On this page" TOC via local Tocbot
@laeubi laeubi force-pushed the copilot/fix-b557e6d0-f9ba-4e80-b858-62aea0092bf6 branch from 493e1d6 to cbdd559 Compare March 22, 2026 11:18
Introduces a new AnalysisPlugin extension point to the bnd tool,
allowing plugins to receive callbacks about analysis
decisions—especially the reasoning behind version range choices for
package imports.

Changes:
- Add AnalysisPlugin interface in aQute.bnd.service, enabling plugins to
  receive notifications about version range decisions and other analysis
events
  during the bundle analysis phase. The interface extends OrderedPlugin
and provides reportImportVersion() and reportAnalysis() callbacks.
- Integrate AnalysisPlugin callbacks into Analyzer: call
reportImportVersion()   on all registered AnalysisPlugin instances
whenever a version range is determined for an import, including a
human-readable explanation for the decision.
- Bump aQute.bnd.service package version from 4.9.0 to 4.10.0 to reflect
the minor (backward-compatible) API addition of the new AnalysisPlugin
interface.
- Add comprehensive test suite (AnalysisPluginTest) verifying that
plugins are called, receive correct version decision data, and respect
plugin ordering.
- Add documentation page describing the AnalysisPlugin interface, usage
  examples, and typical use cases for tracking and logging analysis
decisions.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
@laeubi laeubi force-pushed the copilot/fix-b557e6d0-f9ba-4e80-b858-62aea0092bf6 branch from cbdd559 to 86e80b0 Compare March 22, 2026 11:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a way for collecting analysis results in the Analyzer

6 participants